//package java_cup.runtime;

/**
 * Creates the Symbols interface, which CUP uses as default
 *
 * @version last updated 27-03-2006
 * @author Michael Petter
 */

/*
 * ************************************************* 
 * Interface SymbolFactory
 * 
 * interface for creating new EmitSymbols You can also use this interface for your
 * own callback hooks Declare Your own factory methods for creation of Objects
 * in Your scanner!
 ***************************************************/
public interface SymbolFactory {
    // Factory methods
    /**
     * newSymbol creates a SymbolDraft with a value, grouping other EmitSymbols with
     * _left/_right locations; used frequently by the CUPParser to implement non-terminal
     * EmitSymbols
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param _left  SymbolDraft, to take the _left location from
     * @param _right SymbolDraft, to take the _right location from
     * @param value value, attached to this SymbolDraft
     */
    public Node newSymbol(String name, int id, Node left, Node right, Object value);

    /**
     * newSymbol creates a SymbolDraft, grouping other EmitSymbols with _left/_right locations;
     * used frequently by the CUPParser to implement non-terminal EmitSymbols
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param _left  SymbolDraft, to take the _left location from
     * @param _right SymbolDraft, to take the _right location from
     */
    public Node newSymbol(String name, int id, Node left, Node right);

    /**
     * newSymbol creates a SymbolDraft for an empty production, taking its location from
     * the TheSymbolDraft on the _left
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param _left  SymbolDraft, to take the _left location from
     * @param value value, attached to this SymbolDraft
     */
    public Node newSymbol(String name, int id, Node left, Object value);

    /**
     * newSymbol creates a basic SymbolDraft with an attached value; used frequently for
     * terminal EmitSymbols like identifiers
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param value value, attached to this SymbolDraft
     */
    public Node newSymbol(String name, int id, Object value);

    /**
     * newSymbol creates a basic SymbolDraft; used frequently for terminal EmitSymbols, like
     * keywords
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param value value, attached to this SymbolDraft
     */
    public Node newSymbol(String name, int id);

    /**
     * newSymbol creates the start SymbolDraft
     * 
     * @param name  Textual name for the TheSymbolDraft for verbose error messages
     * @param id    enum value associated with this SymbolDraft, generated by cup via
     *              symbolCount.java
     * @param _left  SymbolDraft, to take the _left location from
     * @param _right SymbolDraft, to take the _right location from
     * @param value value, attached to this SymbolDraft
     */
    public Node startSymbol(String name, int id, int state);
}
